TMAP 모바일 API 개발자 가이드

1. TMAP API 개요 및 핵심 기능

1.1 TMAP API 소개: 대한민국 No.1 모빌리티 플랫폼의 기술력

TMAP API는 단순한 지도 응용 프로그램 인터페이스(API)를 넘어, 티맵모빌리티가 제공하는 대한민국 최고의 종합 모빌리티 플랫폼 기술을 외부 개발자들이 활용할 수 있도록 개방한 것이다.1 SK텔레콤은 2017년부터 TMAP, 사물인터넷(IoT) 등 자사의 핵심 기술 자산을 외부 개발자 및 기업과 공유하여 새로운 가치를 창출하기 위한 ’SK open API 포털’을 운영하고 있으며, TMAP API는 이 포털의 핵심 서비스 중 하나다.2

TMAP은 지난 20년간 대한민국 내비게이션 서비스를 대표해 온 브랜드로, 현재 2,000만 명에 달하는 가입자와 65%의 압도적인 시장 점유율을 기록하고 있다.1 이는 TMAP API가 방대한 실제 사용자 데이터를 기반으로 한, 살아있는(Live) 플랫폼임을 의미한다. 개발자는 이 API를 통해 단순히 지도를 띄우는 것을 넘어, 수십 년간 축적된 고품질의 교통 데이터와 사용자 경험 노하우를 자신의 서비스에 직접 통합할 수 있다.

SK텔레콤의 API 포털은 TMAP을 중심으로 한 생태계 구축을 지향한다. 향후 인증 보안 기술(FIDO), 클라우드 기반 보안 솔루션(SSM) 등 다양한 기반 기술이 지속적으로 공개될 계획이므로, TMAP API를 도입하는 것은 단순한 지도 기능 추가가 아니라 SK 그룹이 제공하는 확장 가능한 기술 인프라에 연결되는 전략적 선택이 될 수 있다.4 이는 개발자에게 향후 서비스 확장에 있어 더 넓은 가능성을 제공한다.

1.2 기술적 특장점: 실시간 데이터와 뛰어난 호환성

TMAP API의 경쟁력은 세 가지 핵심 기술적 특장점에서 비롯된다. 이는 개발자가 위치 기반 서비스를 구현할 때 직면하는 가장 큰 난제인 데이터의 정확성, 풍부함, 그리고 개발 환경의 유연성을 해결해 준다.

첫째, 빠르고 정확한 실시간 콘텐츠를 제공한다. TMAP API는 전국 도로 상황에 대한 실시간 정보를 거의 지연 없이 제공한다.1 사용자는 API를 통해 현재의 교통 흐름을 지도 위에 시각화할 수 있을 뿐만 아니라, 이를 바탕으로 최적 경로를 동적으로 재탐색할 수 있다. 갑작스러운 사고 구간, 공사로 인한 통제 구역, 상습 정체 구간 등을 실시간으로 회피하는 경로를 사용자에게 제시함으로써 서비스의 만족도를 극대화할 수 있다. 이는 특히 배송 시간 예측, 물류 차량 관제 등 시간 정확성이 비즈니스의 핵심인 분야에서 강력한 차별점이 된다.

둘째, 신뢰성이 검증된 방대한 데이터를 보유하고 있다. TMAP은 오랜 서비스 기간 동안 축적한 고품질, 고정밀 데이터를 기반으로 최고의 신뢰성을 자랑한다.1 특히 국내 환경에 최적화된 방대한 POI(Point of Interest, 관심 장소) 데이터는 타의 추종을 불허한다. 약 3,800만 건의 지번 주소, 800만 건의 새 주소와 더불어, 530만 건의 기본 POI, 1,100만 건의 별칭 POI(예: ‘강남역 스타벅스’ 등 사용자가 실제 사용하는 명칭), 그리고 약 800만 건의 기업 특화 POI 데이터는 개발자가 어떤 종류의 위치 기반 검색 기능을 구현하든 풍부하고 정확한 결과를 보장한다.1

셋째, 뛰어난 호환성을 지원한다. TMAP API는 특정 플랫폼에 종속되지 않고 다양한 개발 환경을 지원하여 개발의 유연성을 극대화한다.1 모바일 환경을 위한 Android, iOS 네이티브 SDK는 물론, 웹 환경을 위한 JavaScript SDK, 그리고 최근 각광받는 크로스플랫폼 환경인 Flutter SDK까지 제공한다.5 또한, 플랫폼에 구애받지 않고 서버 사이드에서 TMAP의 핵심 기능을 호출할 수 있는 RESTful API도 완벽하게 지원한다.5 개발자는 이러한 다양한 SDK와 API를 활용하여 신규 서비스를 빠르고 쉽게 개발하거나, 기존 서비스에 TMAP의 강력한 기능을 추가하여 서비스의 가치를 한층 높일 수 있다.

1.3 주요 기능 및 활용 사례

TMAP API는 단순한 지도 표출 기능을 넘어, 모빌리티와 관련된 거의 모든 기능을 API 그룹 형태로 제공하여 개발자가 필요한 기능을 선택적으로 조합하여 사용할 수 있도록 설계되었다.6

주요 기능 그룹:

지도 보기: 지도를 생성하고 확대/축소, 이동, 마커 및 폴리곤 표기 등 기본적인 지도 제어 기능을 제공한다.
POI 검색: 명칭, 전화번호, 카테고리 등 다양한 조건으로 관심 장소를 검색한다.
지오코딩: 주소와 좌표를 상호 변환하여 텍스트 기반의 주소 정보를 지도 위에 시각화하거나, 지도 위의 특정 지점 주소를 확인한다.
경로 안내: 자동차 및 보행자 경로를 탐색한다. 실시간 교통정보를 반영한 최적 경로를 제공하는 것이 핵심이다.
다중 경유지 안내 및 최적화: 여러 경유지를 포함하는 경로를 탐색하거나, 방문 순서가 정해지지 않은 경유지들의 최적 방문 순서를 계산하여 물류 효율을 극대화한다.
교통정보: 특정 도로 구간의 실시간 교통 상황 및 돌발 정보(사고, 공사)를 조회한다.
지오펜싱: 특정 지역(행정구역 등)의 경계 데이터를 제공하고, 특정 객체가 해당 지역에 진입하거나 이탈하는 이벤트를 감지하는 데 활용된다.

이러한 기능들은 이미 다양한 산업 분야에서 성공적으로 활용되며 그 가치를 입증하고 있다.

주요 활용 사례:

배달 및 O2O 서비스 (배달의민족): 풍부하고 정확한 POI 데이터를 활용하여 사용자가 모바일 앱에서 음식점 위치를 정확히 검색하고 확인하는 기능을 제공한다.1 이는 주문 정확도를 높이고 배달 기사의 위치 파악을 용이하게 하여 서비스 품질을 향상시킨다.
물류 및 관제 시스템 (C&U 편의점): 위치 정보 검색과 다중 경로 안내 기능을 활용하여 물류 차량을 실시간으로 관제한다.1 실시간 교통정보를 반영한 최적 길안내를 통해 배송 시간을 단축하고, 차량 도착 예정 시간을 고객에게 정확히 알리며, 지오펜싱 기술로 관할 구역 관리를 자동화하여 운영 효율성을 높인다.
유통 및 당일 배송 시스템 (이마트, 롯데마트): 다중 경유지 안내 및 최적화 기능을 활용하여 효과적인 당일 배송 및 초고속 물류 시스템을 구축했다.1 온라인 주문을 실시간으로 접수하고, TMAP의 경로 정보를 이용해 최적의 배송 순서와 시간을 산출하여 고객이 원하는 시간대에 정확하게 배송을 완료한다. 이는 오프라인 매장을 물류 거점으로 활용하는 혁신적인 비즈니스 모델의 핵심 기술로 작용했다.

2. API 사용 준비: 인증 및 키 발급

TMAP API를 사용하기 위한 첫 단계는 개발자 계정을 등록하고 API 호출에 필요한 인증 키를 발급받는 것이다. 이 과정은 SK open API 포털을 통해 체계적으로 관리되며, 프로젝트별로 API 사용량을 추적하고 보안을 관리할 수 있는 구조로 설계되어 있다.

2.1 개발자 등록 및 프로젝트(앱) 생성

TMAP API의 모든 기능은 SK open API 포털을 통해 제공되므로, 가장 먼저 해당 사이트에서 개발자 계정을 생성해야 한다.7 개인 또는 사업자 회원으로 가입할 수 있으며, 기존 T아이디가 있다면 연동하여 가입할 수도 있다.8

회원 가입 및 로그인 후, API를 사용할 프로젝트를 생성해야 한다. SK open API 포털에서는 이 프로젝트를 ’앱(App)’이라는 단위로 관리한다.7 ’앱’은 개발자가 만들고자 하는 특정 서비스나 애플리케이션을 의미하며, 하나의 ’앱’에 여러 TMAP API 상품을 추가하여 사용할 수 있다. ’앱’을 생성하는 절차는 다음과 같다.

SK open API 포털에 로그인한 후, 우측 상단의 ‘대시보드’ 또는 ’마이페이지’로 이동한다.8
좌측 메뉴에서 ’앱’을 선택한다.
‘앱’ 화면 우측 상단의 ‘앱 만들기’ 버튼을 클릭한다.
팝업 창에 생성할 ’앱’의 이름을 입력하고 확인을 누르면 생성이 완료된다.10

이 ‘앱’ 중심의 관리 모델은 단순히 API를 사용하기 위한 절차를 넘어, 기업 환경에서의 체계적인 관리를 목적으로 설계되었다. 각 ’앱’은 고유한 API 키를 가지며, 사용량 통계, 과금, 멤버 관리가 독립적으로 이루어진다.10 따라서 실제 서비스를 개발할 때는 개발(Development), 스테이징(Staging), 운영(Production) 환경별로 별도의 ’앱’을 생성하여 관리하는 것이 권장된다. 이는 환경 간의 격리를 통해 보안을 강화하고(예: 개발용 키 유출 시 운영 환경에 영향 없음), 각 환경의 API 사용량을 정확히 추적하여 비용을 효율적으로 관리하는 데 매우 효과적인 전략이다.

2.2 API Key (appKey) 발급 및 관리

API 호출 시 개발자를 식별하고 권한을 확인하는 데 사용되는 인증 키가 바로 appKey다. appKey는 ‘앱’ 단위로 발급되며, 다음과 같은 절차를 통해 획득할 수 있다.

앞서 생성한 ’앱’을 선택한 후, ‘Service’ 또는 ‘상품’ 탭으로 이동한다.
사용하고자 하는 TMAP API 상품(예: TMAP API - Free)을 찾아 ’구매하기’를 클릭한다. 무료 요금제도 ‘구매’ 절차를 통해 ’앱’에 추가해야 한다.7
상품이 ’앱’에 성공적으로 추가되면, 해당 ’앱’에 대한 appKey가 자동으로 발급된다.11
발급된 appKey는 ‘앱’ 상세 화면의 ‘앱키(appKey)’ 탭에서 언제든지 확인할 수 있다.10

이 appKey는 API 호출의 핵심이므로 안전하게 관리해야 한다. 만약 키가 외부에 유출되었다고 의심될 경우, ‘앱키(appKey)’ 탭의 ‘재발급’ 기능을 사용하여 새로운 키를 즉시 발급받을 수 있다. 키를 재발급하면 보안 강화를 위해 기존 키는 24시간의 유예 기간을 거친 후 자동으로 삭제된다.10 서비스 중단을 방지하기 위해서는 키 재발급 후 24시간 이내에 애플리케이션에 새로운 키를 적용해야 한다.

2.3 API 호출 기본 구조 및 인증

발급받은 appKey를 사용하여 TMAP REST API를 호출할 수 있다. 모든 API 요청은 표준 HTTP/HTTPS 프로토콜을 따르며, 공통적으로 다음과 같은 구조를 가진다.12

HTTP Method: 각 API 기능에 따라 GET 또는 POST 방식을 사용한다.
Request URL (Endpoint): API의 기본 주소와 특정 기능을 나타내는 경로로 구성된다. (예: https://apis.openapi.sk.com/tmap/routes)
Headers: 요청에 대한 메타데이터를 포함하며, TMAP API에서는 두 가지 헤더가 필수적이다.
appKey: 발급받은 appKey 값을 여기에 포함하여 인증을 수행한다.
Accept: 응답받을 데이터 형식을 지정한다. application/json (기본값), application/xml, application/javascript (JSONP용) 등을 사용할 수 있다.13
Parameters/Body: GET 요청의 경우 URL에 쿼리 스트링(?key=value&...) 형태로 파라미터를 전달하고, POST 요청의 경우 요청 본문(Body)에 데이터를 담아 전달한다.

아래는 POI 검색 API를 호출하는 기본적인 cURL 예제다. 이 예제는 appKey를 헤더에 포함하여 인증하는 방식을 명확하게 보여준다.

curl --request GET \
--url 'https://apis.openapi.sk.com/tmap/pois?version=1&searchKeyword=SKT타워&count=1' \
--header 'accept: application/json' \
--header 'appKey: {YOUR_APP_KEY}'

위 코드에서 {YOUR_APP_KEY} 부분을 실제 발급받은 appKey로 교체하여 실행하면 API가 정상적으로 호출된다.

3. 핵심 REST API 활용 가이드

TMAP API는 다양한 기능을 RESTful API 형태로 제공하여 서버 사이드 개발이나 특정 플랫폼에 종속되지 않는 유연한 개발을 지원한다. 본 파트에서는 가장 핵심적이고 빈번하게 사용되는 REST API들의 상세 명세를 설명한다.

3.1 자동차 경로 안내 API (`/tmap/routes`)

자동차 경로 안내 API는 TMAP의 핵심 기능인 실시간 교통정보를 반영한 길 안내 기능을 제공한다. 물류, 배송, 관제, 호출 서비스 등 모빌리티 관련 서비스의 근간을 이루는 가장 중요한 API다.

기능: 출발지, 목적지, 그리고 최대 5개의 경유지를 설정하여 최적의 자동차 경로를 탐색한다.12
Endpoint: https://apis.openapi.sk.com/tmap/routes
HTTP Method: POST

요청 본문(Body)에 출발지/목적지 좌표, 경로 탐색 옵션 등 다양한 파라미터를 JSON 형식으로 전달한다. 응답으로는 경로를 구성하는 상세 좌표 목록, 각 구간별 안내 정보(도로명, 회전 방향 등), 그리고 전체 경로에 대한 요약 정보(총 거리, 총 소요 시간, 예상 통행료, 예상 택시 요금)를 반환한다.5

이 API의 강력함은 단순히 두 지점을 잇는 것을 넘어, 복잡한 비즈니스 요구사항을 반영할 수 있는 풍부한 파라미터에 있다. 예를 들어, searchOption 파라미터를 통해 ‘교통최적+추천’(기본값), ‘무료도로 우선’, ‘최소시간 우선’, ‘최단거리 우선’ 등 다양한 조건의 경로를 탐색할 수 있다.12 이는 비용과 시간 사이에서 최적의 균형점을 찾아야 하는 물류 서비스에 필수적인 기능이다. 또한

trafficInfo 파라미터를 ’Y’로 설정하면 실시간 교통정보를 반영하여 보다 정확한 도착 예정 시간(ETA)을 계산할 수 있다.5

3.1.1 테이블 1: 자동차 경로 안내 API 주요 요청 파라미터

파라미터	타입	필수	설명	예시 값
`version`	Integer	Y	API 버전. 현재 `1`로 고정.	`1`
`startX`	String	Y	출발지 X좌표 (경도)	`126.98503809`
`startY`	String	Y	출발지 Y좌표 (위도)	`37.56656754`
`endX`	String	Y	목적지 X좌표 (경도)	`127.10331814`
`endY`	String	Y	목적지 Y좌표 (위도)	`37.40304907`
`passList`	String	N	경유지 목록. `X,Y_X,Y` 형식. 최대 5개.	`127.034,37.515_127.055,37.513`
`reqCoordType`	String	N	요청 좌표계 타입.	`WGS84GEO` (기본값)
`resCoordType`	String	N	응답 좌표계 타입.	`WGS84GEO` (기본값)
`searchOption`	String	N	경로 탐색 옵션. `0`: 교통최적+추천, `1`: 무료우선, `2`: 최소시간, `10`: 최단거리 등.12	`0`
`trafficInfo`	String	N	실시간 교통정보 반영 여부.	`Y`
`totalValue`	String	N	검색 결과 반환 옵션. `2`로 설정 시 요약 정보만 반환.12	`2`

3.2 지오코딩 & 리버스 지오코딩 API (`/tmap/geo/...`)

지오코딩은 모든 위치 기반 서비스의 출발점이다. 사용자가 입력한 주소 문자열을 지도에 표시할 수 있는 위경도 좌표로 변환(지오코딩)하거나, 반대로 지도 위의 특정 좌표에 해당하는 주소를 확인(리버스 지오코딩)하는 기능을 수행한다.

지오코딩 (Geocoding)
기능: 지번 주소 또는 도로명 주소를 위경도 좌표로 변환한다.14
Endpoint: https://apis.openapi.sk.com/tmap/geo/geocoding
HTTP Method: GET
주요 파라미터: city_do, gu_gun, dong 등 행정구역 단위를 명확히 지정해야 한다. 주소 입력 시에는 반드시 UTF-8 기반의 URL 인코딩 처리가 필요하다.14
풀텍스트 지오코딩 (Full Text Geocoding)
기능: ’서울특별시 강남구 신사동 500’과 같이 전체 주소 문자열을 한 번에 입력받아 좌표로 변환한다. 보다 유연한 사용자 입력 처리에 용이하다.
Endpoint: https://apis.openapi.sk.com/tmap/geo/fullAddrGeo 15
HTTP Method: GET
주요 파라미터: fullAddr에 전체 주소 문자열을 URL 인코딩하여 전달한다.15
리버스 지오코딩 (Reverse Geocoding)
기능: 위경도 좌표를 주소(지번, 도로명) 정보로 변환한다.5
Endpoint: https://apis.openapi.sk.com/tmap/geo/reversegeocoding
HTTP Method: GET
주요 파라미터: lat, lon에 변환할 위도, 경도 값을 전달한다.

이 API들은 사용자가 입력한 배송지 주소를 검증하고 정확한 위치를 지도에 표시하거나, 사용자의 현재 위치(GPS 좌표)를 주소로 변환하여 화면에 보여주는 등 다양한 시나리오에서 필수적으로 사용된다.

3.3 POI(관심 장소) 통합 검색 API (`/tmap/pois`)

POI 통합 검색 API는 TMAP이 보유한 방대한 장소 데이터를 검색할 수 있는 강력한 도구다. 이를 통해 ‘주변 맛집’, ‘가까운 주유소’, ‘SKT타워’ 등과 같은 사용자 검색어를 처리하는 기능을 구현할 수 있다.

기능: 명칭, 전화번호, 주소, 업종 카테고리 등 다양한 조건으로 POI를 검색한다.6
Endpoint: https://apis.openapi.sk.com/tmap/pois
HTTP Method: GET
주요 파라미터:
searchKeyword: 검색할 키워드
centerLat, centerLon: 중심 좌표 (주변 검색 시)
radius: 검색 반경 (주변 검색 시)
searchtyp: 검색 유형 (명칭, 주소 등)
resCoordType: 응답 좌표계

이 API를 활용하면 배달 앱의 음식점 목록, 내비게이션 앱의 목적지 검색, 지역 정보 앱의 명소 찾기 등 사용자와 상호작용하는 핵심적인 검색 기능을 손쉽게 구현할 수 있다.

3.4 기타 주요 API (다중 경유지, 경유지 최적화 등)

TMAP API는 단순 경로 안내를 넘어 복잡한 물류 및 배송 문제를 해결하기 위한 고급 API들을 제공한다. 이들은 TMAP API를 단순한 지도 도구가 아닌, 정교한 운영 최적화 플랫폼으로 만드는 핵심 기능이다.

다중 경유지 안내 (30개):
기능: 방문 순서가 정해진 여러 경유지(최대 30개)를 포함하는 전체 경로를 한 번에 탐색한다.6 이는 정해진 코스를 순회하는 셔틀버스나 고정된 배송 경로를 가진 차량의 운행 계획 수립에 유용하다.
경유지 최적화 (TSP - Traveling Salesperson Problem):
기능: 방문 순서가 정해지지 않은 여러 경유지(최대 100개)를 입력하면, 모든 경유지를 가장 효율적으로 방문할 수 있는 최적의 순서와 경로를 계산하여 반환한다.6 이는 외판원 문제(TSP)를 해결하는 고도의 알고리즘을 기반으로 하며, 여러 고객에게 상품을 배송해야 하는 퀵서비스, 당일 배송 서비스의 효율을 극적으로 향상시킬 수 있다.
교통정보 API:
기능: 특정 도로 링크(구간)나 지도상의 사각형 영역 내의 실시간 교통 소통 정보, 사고, 공사 등 돌발 정보를 조회한다.6 이를 통해 특정 지역의 교통 상황을 시각적으로 모니터링하는 관제 시스템을 구축하거나, 경로 안내 외의 별도 교통 정보 서비스를 제공할 수 있다.

이러한 고급 API들은 개발자가 복잡한 수학적 알고리즘을 직접 구현할 필요 없이, TMAP의 검증된 엔진을 통해 물류 및 배송 분야의 핵심적인 최적화 문제를 해결할 수 있도록 지원한다.

4. 플랫폼별 SDK 연동 가이드

TMAP API는 모바일 및 웹 애플리케이션에 지도를 쉽게 통합하고 네이티브 기능을 활용할 수 있도록 플랫폼별 SDK(Software Development Kit)를 제공한다. 각 SDK는 해당 플랫폼의 개발 환경에 최적화되어 있어, 개발자는 복잡한 저수준(low-level) API 호출 없이도 풍부한 지도 기능을 구현할 수 있다.

4.1 Android SDK 연동

안드로이드 네이티브 앱에 TMAP 지도를 연동하기 위한 가이드다. Java와 Kotlin 언어 모두에서 사용할 수 있다.

개발 환경 설정:

SK open API 포털의 ‘Resources > SDK&Tools’ 메뉴에서 최신 Android TmapSDK를 다운로드한다.7
다운로드한 파일의 압축을 해제하면 .jar 형식의 라이브러리 파일(예: com.skt.Tmap_x.xx.jar)이 포함되어 있다.
Android Studio에서 프로젝트 뷰를 ’Project’로 변경한 후, app/libs 디렉터리에 해당 .jar 파일을 복사하여 붙여넣는다.7
붙여넣은 .jar 파일을 마우스 오른쪽 버튼으로 클릭하고 ’Add As Library’를 선택하여 프로젝트에 라이브러리를 종속시킨다.7

권한 추가:

지도 데이터를 인터넷을 통해 다운로드하고, 사용자의 현재 위치를 사용하기 위해 AndroidManifest.xml 파일에 아래 권한을 추가해야 한다.7

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

레이아웃에 지도 추가:

지도를 표시할 화면의 XML 레이아웃 파일에 TMapView를 담을 컨테이너(예: LinearLayout)를 추가한다.17

<LinearLayout
android:id="@+id/linearLayoutTmap"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical" />

지도 초기화 및 인증:

Activity 또는 Fragment의 Java/Kotlin 코드에서 TMapView 객체를 생성하고, 발급받은 appKey를 설정하여 인증을 완료한다. 인증이 성공해야 지도가 정상적으로 표시된다.17

// In MainActivity.java
import android.os.Bundle;
import android.widget.LinearLayout;
import androidx.appcompat.app.AppCompatActivity;
import com.skt.Tmap.TMapView;

public class MainActivity extends AppCompatActivity {

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

LinearLayout linearLayoutTmap = (LinearLayout) findViewById(R.id.linearLayoutTmap);
TMapView tMapView = new TMapView(this);

// API Key 설정
tMapView.setSKTMapApiKey("{YOUR_APP_KEY}");

// 초기 지도 설정 (선택 사항)
tMapView.setZoomLevel(15);
tMapView.setMapType(TMapView.MAPTYPE_STANDARD);
tMapView.setLanguage(TMapView.LANGUAGE_KOREAN);

linearLayoutTmap.addView(tMapView);
}
}

위 과정을 마치면 앱 실행 시 지정된 레이아웃에 TMAP 지도가 표시된다. 이후 SDK가 제공하는 다양한 메서드를 호출하여 마커 추가, 경로 그리기, 이벤트 처리 등 복잡한 기능을 구현할 수 있다.19

4.2 iOS SDK 연동

iOS 네이티브 앱(Swift 기반)에 TMAP 지도를 연동하는 절차는 다음과 같다. 현재 Objective-C용 SDK는 지원이 중단되었으므로 Swift 사용이 권장된다.9

개발 환경 설정:

SK open API 포털에서 최신 iOS SDK를 다운로드한다.20 압축을 해제하면 개발용과 배포용 SDK가 포함된 폴더가 나타난다. 시뮬레이터 테스트를 포함한 개발 단계에서는 ‘개발용’ SDK를, 앱스토어 제출 시에는 ‘배포용’ SDK를 사용해야 한다.21
Xcode 프로젝트를 열고, General 탭의 ‘Frameworks, Libraries, and Embedded Content’ 섹션에 다운로드한 TMapSDK.xcframework 파일을 드래그 앤 드롭하여 추가한다.9 ‘Embed & Sign’ 옵션이 선택되었는지 확인한다.

프로젝트 설정:

TMAP 앱과의 연동(Invoke) 기능을 사용하기 위해 Info.plist 파일에 LSApplicationQueriesSchemes 키를 추가하고, 배열의 아이템으로 tmap을 문자열 값으로 추가하는 것이 좋다.9

지도 초기화 및 인증:

지도를 표시할 ViewController에서 TMapSDK를 import하고, TMapViewDelegate 프로토콜을 채택한다.
viewDidLoad 메서드 등에서 TMapView 객체를 생성하고, setApiKey 메서드를 호출하여 발급받은 appKey로 인증을 수행한다.9

// In ViewController.swift
import UIKit
import TMapSDK // SDK 임포트

class ViewController: UIViewController, TMapViewDelegate { // Delegate 채택

var mapView: TMapView?

override func viewDidLoad() {
super.viewDidLoad()

// TMapView 객체 생성
self.mapView = TMapView(frame: self.view.frame)

// Delegate 설정
self.mapView?.delegate = self

// API Key 설정
self.mapView?.setApiKey("{YOUR_APP_KEY}")

// 뷰에 지도 추가
if let mapView = self.mapView {
self.view.addSubview(mapView)
}
}

// TMapViewDelegate 메서드 (예: 지도 로딩 완료 시)
func tMapViewDidLoad() {
print("TMAP 지도 로딩 완료")
// 초기 위치 및 줌 레벨 설정
self.mapView?.setCenter(CLLocationCoordinate2D(latitude: 37.5665, longitude: 126.9780))
self.mapView?.setZoom(15)
}
}

위와 같이 설정하면 iOS 앱에서도 TMAP 지도를 손쉽게 띄우고, Delegate 메서드를 통해 지도의 다양한 이벤트(로딩, 클릭, 이동 등)를 처리할 수 있다.

4.3 Web (JavaScript) SDK 연동

웹 페이지에 TMAP 지도를 연동하기 위한 JavaScript SDK도 제공된다. 이 SDK는 두 가지 주요 버전으로 나뉜다.

Raster Map (V2): 서버에서 생성된 지도 이미지를 타일 형태로 받아와 표시하는 전통적인 방식이다. 구현이 비교적 간단하고 가볍지만, 지도를 확대/축소할 때 약간의 계단 현상이 발생할 수 있으며, 지도 회전과 같은 부드러운 3D 효과는 제한된다.22
Vector Map (V3): 지도 데이터를 벡터 형태로 받아와 클라이언트(브라우저)에서 실시간으로 렌더링하는 방식이다. 확대/축소 시에도 선명함을 유지하며, 지도의 자유로운 회전 및 기울기 조절(Pitch)이 가능하여 훨씬 부드럽고 동적인 사용자 경험을 제공한다.22

프로젝트의 요구사항에 따라 적절한 버전을 선택해야 한다. 단순한 위치 표기가 목적이라면 V2로도 충분하지만, 사용자에게 인터랙티브하고 몰입감 있는 지도 경험을 제공하고자 한다면 V3 벡터맵 사용이 권장된다.

연동 방법은 HTML 파일에 TMAP JavaScript 라이브러리를 <script> 태그로 포함하고, 지도를 표시할 <div> 요소를 지정한 후, JavaScript 코드에서 appKey와 함께 지도 객체를 생성하여 초기화하는 방식으로 이루어진다.

5. 요금 정책 및 사용량 관리

TMAP API는 개발 초기 단계부터 대규모 상용 서비스까지, 비즈니스의 성장에 맞춰 유연하게 대응할 수 있는 다단계 요금 정책을 제공한다. 비용을 효율적으로 관리하고 서비스 중단을 예방하기 위해서는 각 요금제의 특징과 사용량 모니터링 방법을 정확히 이해하는 것이 중요하다.

5.1 요금제 비교 분석

TMAP API의 요금제는 크게 세 가지로 구분된다: 무료(Free), 정액제(Lite), 후불 종량제(Premium).23

Free (무료체험):
비용: 월 기본료 없이 무료로 사용할 수 있다.
제한: 일일 API 호출량에 제한이 있다 (예: 10,000건).25 이 한도를 초과하면 API 호출이 자동으로 차단되어 서비스가 일시 중단될 수 있다.
용도: 개인 프로젝트, 기능 테스트, 서비스 프로토타이핑 및 개발 초기 단계에 적합하다. 상용 서비스를 출시하기 전에 TMAP API의 기능을 충분히 검토하고 개발하는 데 유용하다.26
Lite (정액제):
비용: 월 2,200,000원(VAT 포함)의 고정된 비용을 지불한다.23
제한: 무료 요금제보다 훨씬 높은 일일 호출 한도(예: 50,000건)를 제공한다.25 이 한도를 초과하면 마찬가지로 API 호출이 차단된다.
용도: API 호출량이 일정 수준 이상으로 꾸준히 발생하여 예측 가능한 중소규모의 상용 서비스에 적합하다. 추가 요금에 대한 걱정 없이 안정적으로 서비스를 운영하고자 할 때 선택할 수 있다.
Premium (후불 종량제):
비용: 월 기본료는 없으며, 실제 API를 호출한 만큼 비용을 지불한다. 각 API마다 건당 단가가 책정되어 있다 (예: POI 검색 1.1원/건, RoadAPI 22원/건 등).23
제한: 호출량에 대한 물리적인 제한이 없으므로 대규모 트래픽을 처리할 수 있다.
용도: API 사용량이 많거나, 월별 또는 이벤트에 따라 사용량 변동이 큰 대규모 상용 서비스에 가장 적합하다. 사용한 만큼만 비용을 지불하므로 합리적인 비용 관리가 가능하다.

5.1.1 테이블 2: TMAP API 요금제 비교

구분	Free	Lite	Premium
월 기본료	0원	2,200,000원 (VAT 포함)	0원
과금 방식	무료	월정액	후불 종량제
일일 호출 한도	10,000건 25	50,000건 25	제한 없음 (사용한 만큼 과금)
초과 시 정책	자동 차단	자동 차단	건당 과금
주요 API 건당 요금	-	-	POI 검색: 1.1원, RoadAPI: 22원 등 23
특징	개발 및 테스트용	안정적인 트래픽 예상 시	사용량 변동이 크거나 대량 사용 시

5.2 사용량 모니터링 및 관리

효율적인 비용 관리와 안정적인 서비스 운영을 위해서는 API 사용량을 지속적으로 모니터링하는 것이 필수적이다. SK open API 포털은 이를 위한 강력한 대시보드 기능을 제공한다.

개발자는 포털에 로그인 후 ‘대시보드’ > ‘앱’ 메뉴로 이동하여 자신이 생성한 ‘앱’ 목록을 확인할 수 있다.10 특정 ’앱’을 선택하면 해당 ’앱’의 API 사용 현황을 상세하게 파악할 수 있다. ‘통계’ 탭에서는 다음과 같은 정보를 제공한다.

사용 통계: 특정 기간 동안 각 API 상품이 얼마나 호출되었는지 그래프와 표 형태로 확인할 수 있다. 이를 통해 어떤 기능이 가장 많이 사용되는지, 현재 요금제의 한도에 얼마나 근접했는지 직관적으로 파악할 수 있다.
에러 통계: API 호출 시 발생한 에러의 유형과 빈도를 확인할 수 있다. 이는 애플리케이션의 잠재적인 문제를 조기에 발견하고 디버깅하는 데 큰 도움이 된다.

개발자는 이 통계 데이터를 주기적으로 확인하여 서비스의 트래픽 추이를 분석하고, 현재 요금제가 적절한지 판단해야 한다. 만약 사용량이 꾸준히 증가하여 무료 또는 정액제 요금제의 한도에 근접하고 있다면, 서비스 중단을 방지하기 위해 사전에 상위 요금제로 변경하는 것을 고려해야 한다.

6. 에러 코드 및 문제 해결

API 연동 개발 과정에서 발생하는 에러를 신속하게 진단하고 해결하는 것은 매우 중요하다. TMAP API의 에러는 크게 두 가지 범주로 나뉜다. 첫째는 API 호출의 가장 앞단에서 발생하는 ’API 게이트웨이 공통 에러’이고, 둘째는 TMAP 서비스 자체의 로직과 관련된 ’TMAP API 고유 에러’다.

6.1 API 게이트웨이 공통 에러

API 게이트웨이 에러는 주로 인증, 권한, 호출량 제한 등 API 호출의 기본적인 유효성과 관련된 문제로 인해 발생한다. 애플리케이션의 로직보다는 API 호출 설정 자체를 먼저 점검해야 한다.

6.1.1 테이블 3: API 게이트웨이 공통 에러 코드

HTTP 상태	에러 코드	메시지	원인 및 해결 방안
401	`UNAUTHORIZED`	Unauthorized	`appKey`가 요청 헤더에 누락됨. 모든 API 요청 헤더에 `appKey` 필드를 정확히 포함했는지 확인한다.27
403	`INVALID_API_KEY`	Forbidden	`appKey` 값이 유효하지 않음. SK open API 포털 대시보드에서 발급받은 정확한 키 값을 복사하여 사용한다.27
403	`ACCESS_DENIED`	Authorized IP Address only	`appKey`에 특정 IP만 허용하도록 Whitelist가 설정된 경우, 허용되지 않은 IP에서 API를 호출함. 포털에서 IP 설정을 확인하거나 서버 IP를 추가한다.28
429	`QUOTA_EXCEEDED`	Limit Exceeded	계약된 요금제의 일일/월간 호출량(SLA)을 초과함. 대시보드에서 사용량을 확인하고, 필요한 경우 요금제 업그레이드를 고려한다.27
429	`THROTTLED`	Too Many Requests	초당 호출 건수(TPS) 제한을 초과함. 짧은 시간에 너무 많은 요청을 보낸 경우로, API 호출 사이에 적절한 시간 간격(delay)을 두거나 재시도 로직을 구현한다.27
500	`API_CONFIGURATION_ERROR`	Internal server error	API 게이트웨이 내부 시스템 오류. 일시적인 문제일 수 있으므로 잠시 후 재시도하고, 문제가 지속되면 고객지원에 문의한다.27

6.2 TMAP API 고유 에러

이 에러들은 API 게이트웨이를 정상적으로 통과한 후, TMAP API 서버 내부에서 요청을 처리하는 과정에서 발생하는 문제들이다. 주로 요청 파라미터의 형식이나 값이 잘못된 경우에 발생한다.

6.2.1 테이블 4: TMAP API 고유 에러 코드

HTTP 상태	에러 코드	메시지 (예시)	원인 및 해결 방안
204	-	No Content	정상적인 요청이었으나 조건에 맞는 검색 결과가 없는 경우. 또는 리버스 지오코딩 시 대한민국 범위를 벗어난 좌표를 요청하는 등 유효하지 않은 입력으로 인해 결과가 없는 경우다.27
400	`1100`	요청 데이터 오류입니다.	가장 일반적인 파라미터 오류. 필수 파라미터가 누락되었거나, 파라미터의 데이터 타입(숫자, 문자열, 범위 등)이 API 명세와 다름. 해당 API의 공식 문서를 참고하여 모든 파라미터의 형식과 값을 재확인한다.27
400	`1006`	잘못된 좌표 형식입니다.	위경도 좌표 값에 숫자 외의 문자(예: 공백, 특수문자)가 포함됨. 좌표 값의 유효성을 검증하는 로직을 추가한다.27
400	`1009`	입력 좌표 오류입니다.	좌표 값이 유효한 범위를 벗어났거나, 경도(X)와 위도(Y) 값이 서로 바뀌어 입력되었을 가능성이 높다. `startX`, `startY` 등의 파라미터 순서를 확인한다.27
400	`2300`	잘못된 주소 형식입니다.	지오코딩 요청 시 입력한 주소의 형식이 올바르지 않음. 주소 체계(지번/도로명)와 `addressFlag` 파라미터 값이 일치하는지 확인하고, 주소에 오탈자가 없는지 점검한다.27
400	`9401`	필수 파라미터가 없습니다.	API 호출에 반드시 필요한 파라미터가 누락됨. API 명세에서 필수(Mandatory)로 지정된 모든 파라미터가 요청에 포함되었는지 확인한다.27
500	`1005`	시스템 오류입니다.	TMAP API 서버 내부의 일시적인 오류. 잠시 후 재시도하고, 문제가 지속적으로 발생하면 요청 파라미터와 함께 고객지원에 문의하여 상세한 분석을 요청한다.27

7. 참고 자료

TMAP - SK open API, https://openapi.sk.com/products/detail?svcSeq=4
“T맵 기술 빌려쓰세요”…SK텔레콤, ‘API 포털’ 오픈 - 한겨레, https://www.hani.co.kr/arti/economy/it/815933.html
“T맵 기술로 신규 서비스 개발”…SKT, ‘API 포털’ 오픈 - 디지털투데이 (DigitalToday), https://www.digitaltoday.co.kr/news/articleView.html?idxno=112666&rf=relatedNews&utm_source=digitaltoday
SKT, T맵 기반 기술 공개…API 포털 오픈 - 아시아경제, http://cm.asiae.co.kr/article/2017102509350065478
T MAP API, https://tmapapi.tmapmobility.com/
TMAP 소개, https://skopenapi.readme.io/reference/t-map-%EC%86%8C%EA%B0%9C
T map API 사용해 지도 띄우기 - 소더코드의 개발자들 그리고, https://sothecode.tistory.com/83
[React] T Map API (1) : 가입하기 - 개발 공부방 - 티스토리, https://zindex.tistory.com/298
[iOS/Swift] T-Map(티맵) 연동하기 - 스펜서 개발블로그, https://spencer.tistory.com/30
앱 키 확인하기 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=126
TMAP - SK open API, https://openapi.sk.com/qnaCommunity/279
자동차 경로 안내 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=46
장소 통합 검색 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=12
SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=24
Full Text Geocoding - SK open API 소개, https://skopenapi.readme.io/reference/full-text-geocoding
T-map API - 데이터를 기반으로 - 티스토리, https://ds92.tistory.com/10
[Android] T-Map API을 사용하여 지도 띄워보기 - 조금씩 꾸준히, https://blog.sungmin.dev/64
[Android] T Map API를 이용하여 어플에 지도 생성하기, https://haem-jsp.tistory.com/20
TMAP API, https://tmapapi.tmapmobility.com/main.html
[Flutter] Tmap API 및 Tmap 앱 연동 (1) - Android편 - 코딩하자 - 티스토리, https://cording-cossk3.tistory.com/210
[iOS] Tmap SDK 2.x 버전 시작하기 - 책 읽는 개발자, https://scshim.tistory.com/184
React에서 TMap API 사용하기, https://ttaerrim.tistory.com/61
SK open API, https://openapi.sk.com/products/calc?svcSeq=4&menuSeq=5
[Flutter] 지도 API 비교 및 사용 방법 - 코딩하자 - 티스토리, https://cording-cossk3.tistory.com/261
TMAP - SK open API, https://openapi.sk.com/qnaCommunity/319
T맵 API Business - T map Trend Map 2020, https://www.tmap.co.kr/static/trendmap_2020/tmap-story/3-05.html
API 게이트웨이 공통 에러 코드, https://openapi.sk.com/products/detail?linkMenuSeq=58
에러 코드 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=318